# MIPI

This document describes how to connect, identify, adjust brightness, use touch functionality, and play video via the **MIPI-DSI** display under the **Quectel Pi M1 / L1 Debian** system. This document uses the Waveshare **8-inch DSI LCD (C)** capacitive touchscreen as an example.

> 💡 **Note**: The **Micro HDMI** and **MIPI-DSI** displays on the Quectel Pi M1 / L1 are mutually exclusive and cannot be used simultaneously as a dual-display output. After switching the display interface, it is recommended to power-cycle and restart the system.

# Overview

**MIPI-DSI** is a high-speed serial display interface designed for display panels, suitable for scenarios such as embedded desktops, touch-interactive terminals, industrial HMIs, and media playback. The Quectel Pi M1 / L1 provides 1 MIPI-DSI display interface, which can be connected to a compatible DSI screen to enter the Debian desktop environment. The M1 defaults to the GNOME desktop, and the L1 defaults to the Weston desktop.

The display-related interfaces of the Quectel Pi M1 / L1 are shown in the table below:

| **Interface** | **Description** |
| --- | --- |
| MIPI-DSI（M1） | 1 FPC connector, based on the MIPI standard, supporting FHD+ (1080 × 2520) @ 60 fps. |
| MIPI-DSI（L1） | 1 FPC connector, based on the MIPI standard, supporting HD+ (1680 x 720) @ 60 fps. |
| Touch | The example screen establishes touch input with the system via a screen adapter board/ribbon cable. Once connected, touch can be used directly on the Debian desktop. |

# Hardware Interface

## Screen Interface Description

The back of the Waveshare 8-inch DSI LCD (C) screen includes a DSI ribbon cable interface and power/touch-related interfaces. When connecting, pay attention to the ribbon cable orientation, the connector latch status, and the screen's power supply method.

```{image} images/image_K38AbbEBFory6pxdnUqc5FHSntd.webp
:width: 3264px
:height: 2324px
```

## M1 / L1 Interface Connection

Connect the MIPI-DSI ribbon cable to the MIPI-DSI FPC connector on the Quectel Pi M1 / Quectel Pi L1, and ensure the ribbon cable is fully inserted and the latch is pressed down firmly. For screen power, follow the screen's hardware instructions, and avoid plugging or unplugging the MIPI ribbon cable while the device is powered on.

```{image} images/image_LeDEb5Xh1oODzJxj4KVc1q10nVb.webp
:width: 1956px
:height: 901px
```

Connection notes:

1. Before connecting or disconnecting the MIPI ribbon cable, turn off the development board's power first.

2. Ensure the ribbon cable's gold finger contacts are oriented correctly to avoid reverse insertion.

3. Ensure the FPC connector latch is pressed down firmly to avoid a black screen or abnormal touch after power-on.

4. If the screen requires an independent power supply, ensure the power connector is stably connected.

# Quick Start

1. Turn off the development board's power.

2. Connect the MIPI-DSI screen following the hardware connection instructions.

3. Power on the screen, and then power on the development board.

4. After the system boots, it will enter the Debian desktop. The M1 enters the GNOME desktop, and the L1 enters the Weston desktop.

5. To check the system status, run the following in the development board terminal:

```bash
hostname -I
cat /sys/class/drm/card0-DSI-1/status
cat /sys/class/drm/card0-DSI-1/modes
cat /sys/class/backlight/2-0045/brightness
cat /sys/class/backlight/2-0045/max_brightness
```

The measured backlight node for the M1 is `/sys/class/backlight/3-0045/`, and for the L1 it is `/sys/class/backlight/2-0045/`. Both the current brightness and maximum brightness are `255`.

M1 MIPI desktop display:

```{image} images/image_CalEb60Gco3mBLxo5Xbcf7V8nO8.webp
:width: 1280px
:height: 800px
```

M1 checking display and backlight status:

```{image} images/image_UOTVbmcDloWoGuxhwoBcWeainfc.webp
:width: 1280px
:height: 800px
```

L1 MIPI desktop display:

```{image} images/image_K4NbbbJ3YoF5HUxCZDRcsDNxnyc.webp
:width: 760px
:height: 427px
```

L1 checking display and backlight status:

```{image} images/image_GRDQbXnmwoAjfDx0b5Gceadrnkc.webp
:width: 1280px
:height: 800px
```

# Feature Usage (GNOME)

The following features are based on the M1 GNOME desktop environment.

## Adjusting Screen Brightness and Volume

After connecting the MIPI screen and entering the Debian desktop, click the status bar area at the top-right corner of the desktop, and you can drag the volume slider and brightness slider in the quick settings panel to adjust the current audio output volume and screen brightness.

```{image} images/image_Zur1bbNMdo4yMax86XEcq0wunTc.webp
:width: 1280px
:height: 800px
```

In addition to the desktop quick settings, MIPI screen brightness can also be checked via the system backlight node. The measured backlight node in this document is `/sys/class/backlight/3-0045/`:

```bash
cat /sys/class/backlight/3-0045/brightness
cat /sys/class/backlight/3-0045/max_brightness
```

To temporarily adjust brightness, run the following command on the development board. This example sets the brightness to `200`:

```bash
echo 200 | sudo tee /sys/class/backlight/3-0045/brightness
```

To restore maximum brightness, run:

```bash
cat /sys/class/backlight/3-0045/max_brightness
sudo sh -c 'cat /sys/class/backlight/3-0045/max_brightness > /sys/class/backlight/3-0045/brightness'
```

> 💡 **Note**: The backlight node name may differ across system versions. If `/sys/class/backlight/3-0045/` does not exist, first run `ls /sys/class/backlight/` to check the actual node name.

## Touch Functionality

After connecting the MIPI screen and entering the Debian desktop, you can directly use the screen's touch functionality for tapping, swiping, and window operations. If touch does not respond, first check whether the screen's touch connection cable, power supply, and I2C/touch-related connections are secure.

## How to Use Video Playback

You can first push a test video to the `Videos` directory on the development board:

```bash
adb push /home/q/work/temp/test-1.mp4 /home/q/Videos/m1-mipi-display-test.mp4
```

**Graphical video playback**: On the Debian desktop, you can navigate to the `Videos` directory via the file manager and double-click `m1-mipi-display-test.mp4` to play it.

```{image} images/image_S8RnbcqE1oAqHsxIZ0HcYc4Inyh.webp
:width: 1280px
:height: 800px
```

```{image} images/image_SM3GbfKzIogThSx7FoScnqWwnSd.webp
:width: 1280px
:height: 800px
```

**GStreamer command-line video playback**: To play video from the command line, enter the following command.

```bash
gst-launch-1.0 playbin uri=file:///home/q/Videos/m1-mipi-display-test.mp4
```

Below is a screenshot of playing video via the GStreamer command line.

```{image} images/image_Irszbx4CUoJLCXxGFm1c4sEsnYg.webp
:width: 1280px
:height: 800px
```

In testing, video played via the desktop file manager and GStreamer command line both displayed correctly on the MIPI screen.

## How to Use Audio Playback

You can first push a test audio file to the `Music` directory on the development board:

```bash
adb push /home/q/work/temp/test.mp3 /home/q/Music/m1-mipi-audio-test.mp3
```

**Graphical audio playback**: On the Debian desktop, you can navigate to the `Music` directory via the file manager and double-click `m1-mipi-audio-test.mp3` to play it.

```{image} images/image_OGIXbeRr1okVktxATpEcfJBhnfd.webp
:width: 1280px
:height: 800px
```

```{image} images/image_CHgEbx7XYoAQIgxdka4c0lcvnBc.webp
:width: 1280px
:height: 800px
```

**GStreamer command-line audio playback**: To play audio from the command line, enter the following command.

```bash
gst-launch-1.0 playbin uri=file:///home/q/Music/m1-mipi-audio-test.mp3
```

Below is a screenshot of playing audio via the GStreamer command line.

```{image} images/image_NSmKbIb6ioe2VIx1MPscqrWyneg.webp
:width: 1280px
:height: 800px
```

In testing, audio played via the desktop file manager and GStreamer command line both produced sound correctly on the current audio output device. If using an external Bluetooth speaker or other audio device, ensure the system's audio output device is correctly selected.

## Audio Output Check

If there is no sound during video playback, first check the audio service and default output device:

```bash
pactl info
```

If there are multiple audio output devices in the system, you can switch output devices in the quick settings panel at the top-right corner of the GNOME desktop, or go to **Settings > Sound** to view the audio output configuration.

# Feature Usage (Weston)

The following features are based on the L1 Weston desktop environment.

## Touch Functionality

After connecting the MIPI screen and entering the Debian desktop, you can directly use the screen's touch functionality for tapping, swiping, and window operations. If touch does not respond, first check whether the screen's touch connection cable, power supply, and I2C/touch-related connections are secure.

## How to Use Video Playback

You can first push a test video from the host to the `Videos` directory on the development board:

```bash
adb push /home/q/work/temp/test-1.mp4 /home/q/Videos/l1-mipi-display-test.mp4
```

**GStreamer command-line video playback**: To play video from the command line on the Weston desktop, enter the following command.

```bash
export XDG_RUNTIME_DIR=/run/user/root
export WAYLAND_DISPLAY=wayland-1
gst-launch-1.0 playbin uri=file:///home/q/Videos/l1-mipi-display-test.mp4 video-sink="waylandsink fullscreen=false x=160 y=128 width=960 height=544" audio-sink=pulsesink
```

> 💡 **Note**: In the tested environment, Weston was started as the `root` user with the Wayland socket at `/run/user/root/wayland-1`, so command-line video playback requires setting `XDG_RUNTIME_DIR=/run/user/root` and `WAYLAND_DISPLAY=wayland-1`. The above command uses `videoscale` and `waylandsink` to output the video as a 960x544 centered window. If your Weston runs under a different user, socket, or resolution, adjust accordingly based on your actual environment.

In testing, video played via the GStreamer command line displayed correctly as a centered video window on the MIPI screen.

```{image} images/image_MAr2btHYCoeUb1x3gXKcQc3XnFh.webp
:width: 1280px
:height: 800px
```

## How to Use Audio Playback

You can first push a test audio file from the host to the `Music` directory on the development board:

```bash
adb push /home/q/work/temp/test.mp3 /home/q/Music/l1-mipi-audio-test.mp3
```

**GStreamer command-line audio playback**: To play audio from the command line, enter the following command.

```bash
gst-launch-1.0 playbin uri=file:///home/q/Music/l1-mipi-audio-test.mp3
```

In testing, audio played via the GStreamer command line produced sound correctly on the current audio output device. During testing, a Bluetooth headset was connected, and the PulseAudio default output device was `bluez_sink.*.a2dp_sink`. If using an external Bluetooth speaker, Bluetooth headset, or other audio device, ensure the system's audio output device is correctly selected.

```{image} images/image_VZk0bwQ2hod1Pjxl59Rc0BX2nng.webp
:width: 1119px
:height: 511px
```

# Advanced Features

## Automatic Display Mode

After the MIPI screen is connected, the system loads the display driver and outputs the desktop during the boot phase. Since MIPI-DSI is not designed for hot-plugging, it is recommended to complete the ribbon cable connection while the device is powered off, then power it on.

## Command-Line Status Check

Common troubleshooting commands are as follows:

```bash
# List backlight nodes
ls /sys/class/backlight/

# Check MIPI/DSI connection status and display modes
cat /sys/class/drm/card0-DSI-1/status
cat /sys/class/drm/card0-DSI-1/modes

# Check backlight brightness (M1 backlight node is 3-0045, L1 is 2-0045)
cat /sys/class/backlight/3-0045/brightness
cat /sys/class/backlight/3-0045/max_brightness

# View display-related information in system logs
journalctl -b | grep -Ei 'dsi|mipi|drm|panel|backlight'
```

# Application Scenarios

- **Media entertainment terminal**: Play video, music, or display images via a MIPI screen.

- **Industrial data visualization platform**: Used to display device status, sensor data, dashboards, and alarm information.

- **Smart interactive terminal**: Combined with a touchscreen to implement local menus, control panels, and human-machine interaction interfaces.

- **Development and debugging display terminal**: View the Debian desktop and debugging information without needing an additional HDMI monitor.

# Troubleshooting

| **Symptom** | **Possible Cause** | **Solution** |
| --- | --- | --- |
| Black screen after power-on | The MIPI ribbon cable is not fully inserted, inserted in the wrong orientation, the screen power supply is abnormal, or the system did not correctly load the display driver | Power off, then re-check the ribbon cable orientation, FPC latch, and screen power supply; after re-powering, check system logs via serial console or ADB. |
| Screen artifacts or flickering | Poor ribbon cable contact, poor ribbon cable quality, unstable screen power supply, or interference | Re-plug and secure the ribbon cable, check the power supply, and avoid running the cable near strong sources of interference. |
| Touch not responding | Touch-related connections are not properly connected, or the touch driver is not loaded correctly | Check the screen's touch connection cable and power supply; check system logs for touch/I2C-related errors. |
| Brightness not adjustable | The backlight node name differs from the example in this document, or the current system does not expose a backlight adjustment interface | Run `ls /sys/class/backlight/` to find the actual node, and read or write brightness values using the actual node path. |
| Video cannot be played | The video codec is not supported by the current player, or the file path is incorrect | Confirm that the video file exists under `/home/q/Videos/`; for the M1, try using the GNOME video player or GStreamer; for the L1, try using GStreamer command line to play a common H.264 MP4 test video. |
| Video has picture but no sound | The audio output device is incorrectly selected, the volume is muted, or the audio device is not connected | For the M1, check the sound settings in the top-right corner, run `pactl info` to check the default output device; for the L1, confirm that the audio device is connected and that the volume is not muted. |
| No display after switching display interfaces | MIPI and Micro HDMI are connected simultaneously, or the system was not restarted after switching interfaces | Keep only the target display interface connected, power off, and then re-power to start the system. |